<HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" content="text/html;" /> <!-- charset=us-ascii"> -->
<TITLE>Dingo API Reference</TITLE>
</HEAD>
<BODY>

<p>
<a name="package_Project">
<h2>The <code>Dingo.Project</code> package</h2>
<p>
The user code package hierarchy will be rooted in the <code>Dingo.Project</code>
package, so your <code>main.py</code> file will be the module
<code>Dingo.Project.main</code>. Other modules in this package should be
imported explicitly to avoid possible name conflicts, e.g.:
<p>
<code>import Dingo.Project.my_module as my_module</code>

<P>
<a name="timing"></a>
<H2>Timing and Concurrency</H2>
<p>
The following restrictions apply in using the <code>Dingo</code> API:
<ul>
<li>If engaged in a long-running task that does not use the <code>Dingo</code>
API, the code should periodically call the
<A href="#fn_PollNetwork"><code>PollNetwork</code></A> function or else the
application may become unresponsive.
<li>User code should not spawn new threads (not counting those spawned as part
of the sensor instances themselves).
<li>If you wish to pause the currently running thread, use the
<A href="#fn_Sleep"><code>Sleep</code></A> function. Do not use the standard
function <code>time.sleep</code> or similar.
</ul>

<p>
<a name="package_API">
<H2>The <code>Dingo.API</code> package</H2>
<p >
All these classes are in the <code>Dingo.API</code> package, which should be
<code>import</code>ed into user code.

<p >
<ul>
<li><A href="#class_SensorGraph">Class <code>SensorGraph</code></A>
<li><A href="#class_SensorColour">Class <code>SensorColour</code>
  (aka <code>SensorColor</code>)</A>
<li><A href="#class_SensorNode">Class <code>SensorNode</code></A>
<li><A href="#class_SensorArc">Class <code>SensorArc</code></A>
<li><A href="#class_DeletedException">Class <code>DeletedException</code></A>
<li><A href="#fn_PollNetwork">Function <code>PollNetwork</code></A>
<li><A href="#fn_Sleep">Function <code>Sleep</code></A></li>
</ul>

<p >
<a name="class_SensorGraph"></a>
<h2>Class <strong><code>SensorGraph</code></strong></h2>
<p >
This class cannot be instantiated. One instance of it exists, which is
passed to the <code>__init__</code> method of the user's
<code>Simulation</code> subclass. New <code><a href+#class_SensorNode>
SensorNode</a></code>s can be created from it.

<p >
<h3><code>AddSensorNode(<em>self</em>, <em>xy</em>,
<em>colour</em>)</code></h3>
<p >
Creates a new SensorNode at position xy (a 2-tuple of integers) of the given
colour (a <code><A href="#class_SensorColour">SensorColour</code></A>
instance).

<p >
<h3><code>GetNodes(<em>self</em>)</code></h3>
<p >
Returns a (newly-allocated) list of all the nodes on the Graph.

<p >
<h3><code>GetArcs(<em>self</em>)</code></h3>
<p >
Returns a (newly-allocated) list of all the arcs on the Graph.


<p >
<h3><code>ClearGraph(<em>self</em>)</code></h3>
<p >
Removes all nodes and arcs from the Graph.

<p >
<a name="class_SensorColour"></a>
<h2>Class <code>SensorColour</code> (aka <code>SensorColor</code>)</h2>
<p >
This class is used to represent the colour of nodes and arcs. Instances of
this class have well-defined ordering, equality, and hashing semantics. It
should not be instantiated directly; use the static methods documented below.

<p >
<h3><code>GetRed(<em>self</em>)</code></h3>
<p >
<h3><code>GetGreen(<em>self</em>)</code></h3>
<p >
<h3><code>GetBlue(<em>self</em>)</code></h3>
<p >
Return the red, green, and blue intensities repespectively, in range [0-255].

<p >
<h3><code>GetRGB(<em>self</em>)</code></h3>
<p >
Returns the three colour intensities as a tuple.

<p >
<h3><code>GetRGBCombined(<em>self</em>)</code></h3>
<p >
Returns an 24-bit int containing 8 bits for each colour, with red in the
highest-order byte, then green, then blue.

<p >
<h3><code>GetName(<em>self</em>)</code></h3>
<p >
Returns a string representing the name of the colour, or the empty string
if it doesn't have a name.

<p >
<h3><code>FromName(<em>name</em>)</code> (static method)</h3>
<p >
Returns a new colour of that name if it exists, otherwise
throws a ValueError.

<p >
<h3><code>ExistsNamed(<em>name</em>)</code> (static method)</h3>
<p >
Returns whether or not a colour of that name exists.

<p >
<h3><code>FromName(<em>name</em>)</code> (static method)</h3>
<p >
Static method. Returns a new colour of that name if it exists, otherwise
throws a ValueError.

<p >
<h3><code>FromRGB(<em>r</em>, <em>g</em>, <em>b</em>)</code> (static method)</h3>
<p >
Static method. Returns a new colour with given red, green, and blue
intensities.

<p >
<h3><code>FromRGBCombined(<em>rgb</em>)</code> (static method)</h3>
<p >
Static method. Returns a new colour with red, green, and blue intensities
from the given 24-bit int.

<p >
<code>
Aquamarine 
Black 
Blue 
BlueViolet 
Brown 
CadetBlue 
Coral 
CornflowerBlue 
Cyan
DarkGrey 
DarkGreen 
DarkOliveGreen 
DarkOrchid 
DarkSlateBlue 
DarkSlateGrey
DarkTurquoise 
DimGrey 
Firebrick 
ForestGreen 
Gold 
Goldenrod 
Grey 
Green
GreenYellow 
IndianRed 
Khaki 
LightBlue 
LightGrey 
LightSteelBlue 
LimeGreen
Magenta 
Maroon 
MediumAquamarine 
MediumBlue 
MediumForestGreen 
MediumGoldenrod
MediumOrchid 
MediumSeaGreen 
MediumSlateBlue 
MediumSpringGreen 
MediumTurquoise
MediumVioletRed 
MidnightBlue 
Navy 
Orange 
OrangeRed 
Orchid 
PaleGreen 
Pink 
Plum
Purple 
Red 
Salmon 
SeaGreen 
Sienna 
SkyBlue 
SlateBlue 
SpringGreen 
SteelBlue 
Tan
Thistle 
Turquoise 
Violet 
VioletRed 
Wheat 
White 
Yellow 
YellowGreen
</code>
<p >
These static fields are all predefined <code>SensorColour</code>s.


<p >
<a name="class_SensorNode"></a>
<h2>Class <code>SensorNode</code></h2>
<p >
Represents nodes on the Graph. Cannot be instantiated directly. This class also
maintains a set of data points that are plotted on the chart when that node is
selected by the user. In a boolean context, returns whether or not the node is
<em>valid</em>, i.e. whether or not it is still attached to the Graph. All methods
listed here will check that the node is valid before continuing.

<p >
For plotting data, the node maintains a <em>legend</em> and a set of <em>plot
data</em>. These map <em>named</em> colours (i.e. <A href="#class_SensorColour">
<code>SensorColour</code></A>s
whose <code>GetName()</code> method returns a non-empty string) to descriptive
text and the data values respectively. Each trace on the chart is in a different
colour. Data values may be appended to the plot, pushing out the oldest values.
The default setup uses one plot of black markers, 10 points for the x-axis, and
the y-axis in the range [-1,1] inclusive.

<p >
<h3><code>CheckValid(<em>self</em>)</code></h3>
<p >
If this node has been deleted, raises a <A href="#class_DeletedException">
<code>DeletedException</code></A>.

<p >
<h3><code>GetSensorGraph(<em>self</em>)</code></h3>
<p >
Returns the Graph.

<p >
<h3><code>DeleteFromGraph(<em>self</em>)</code></h3>
<p >
Removes itself (and any arcs attached to it) from the Graph.

<p >
<h3><code>GetNodeColour(<em>self</em>)</code> (aka <code>GetNodeColor</code>)</h3>
<p >
Returns a new <code>SensorColour</code> object representing this node's colour.

<p >
<h3><code>SetNodeColour(<em>self</em>, <em>colour</em>)</code> (aka <code>SetNodeColor</code>)</h3>
<p >
Sets this node's colour to the given <code>SensorColour</code> object.

<p >
<h3><code>NodePosition(<em>self</em>)</code></h3>
<p >
Returns a new 2-tuple representing the (x,y)-coordinates of the node.

<p >
<h3><code>MoveNode(<em>self</em>, <em>xy</em>)</code></h3>
<p >
Sets the (x,y)-coordinates of the node to those of the given 2-tuple.

<p >
<h3><code>GetArcFrom(<em>self</em>, <em>fromNode</em>)</code></h3>
<p >
Returns the arc running from <em>fromNode</em> to <em>self</em>, or
<code>None</code> if no such arc exists.

<p >
<h3><code>GetArcTo(<em>self</em>, <em>toNode</em>)</code></h3>
<p >
Returns the arc running from <em>self</em> to <em>toNode</em>, or
<code>None</code> if no such arc exists.

<p >
<h3><code>ArcsFromHere(<em>self</em>)</code></h3>
<p >
Returns a (newly-allocated) list of arcs running from <em>self</em>.

<p >
<h3><code>ArcsToHere(<em>self</em>)</code></h3>
<p >
Returns a (newly-allocated) list of arcs running to <em>self</em>.

<p >
<h3><code>AddArcTo(<em>self</em>, <em>toNode</em>, <em>colour</em>)</code></h3>
<p >
Creates and returns a new arc running from <em>self</em> to <em>toNode</em> of
the given colour.

<p >
<h3><code>SetPlotAxisLabels(<em>self</em>, <em>title</em>="",
  <em>x</em>="", <em>y</em>="")</code></h3>
<p >
Sets the labels for the plot chart axes, and redraws the chart (if selected).

<p >
<h3><code>SetPlotAxes(<em>self</em>, (<em>ymin</em>, <em>ymax</em>),
  <em>xnpoints</em>, <em>xscale</em>=1)</code></h3>
<p >
Sets the y-axis to be [<code>ymin</code>, <code>ymax</code>] (inclusive),
that there be <code>xnpoints</code> points on the x-axis (running back from
zero), with a scale factor of <code>xscale</code>. Clears the plotting data
and (if selected) redraws the chart, now empty.


<p >
<h3><code>GetPlotLegend(<em>self</em>)</code></h3>
<p >
Returns a copy of the legend (mapping named colours to legend text).

<p >
<h3><code>SetPlotLegend(<em>self</em>, <em>legend</em>)</code></h3>
<p >
Sets the legend which defines the data on the plotting chart. If
<code>legend</code> is a string and there is only one item in the
current legend for this node, updates the text of that legend item.
Otherwise this acts as a mapping from named <A href="#class_SensorColour">
<code>SensorColour</code></A> to
legend labels, and plotting data in any colour not in the new legend
will be removed. Redraws the chart, if this node is selected.

<p >
<h3><code>AddPlotData(<em>self</em>, <em>data</em>)</code></h3>
<p >
Acts as a mapping from the colours of the legend to numbers (or, if the
argument is just a number, adds it to the plotting data for all the colours,
useful if there is just one in the legend). The number may be
<code>None</code>, in which case a space is left in that colour's plot on the
chart. Redraws, if selected.

<p >
<h3><code>Replot(<em>self</em>)</code></h3>
<p >
Redraws the data, if this node is selected.

<p >
<a name="class_SensorArc"></a>
<h2>Class <code>SensorArc</code></h2>
<p >
This class represents arcs between nodes on the graph. Arcs have direction,
as indicated by their arrows. Arcs are created by the <code>AddArcTo</code>
method of the <A href="#class_SensorNode"><code>SensorNode</code></A> class.
In a boolean context, returns whether or not the arc is <em>valid</em>, i.e.
whether or not it is still attached to the Graph. All methods listed here
will check that the arc is valid before continuing.

<p >
<h3><code>CheckValid(<em>self</em>)</code></h3>
<p >
If this arc has been deleted, raises a <A href="#class_DeletedException">
<code>DeletedException</code></A>.

<p >
<h3><code>GetSensorGraph(<em>self</em>)</code></h3>
<p >
Returns the Graph.

<p >
<h3><code>DeleteFromGraph(<em>self</em>)</code></h3>
<p >
Removes itself from the Graph.

<p >
<h3><code>GetArcColour(<em>self</em>)</code> (aka <code>GetArcColor</code>)</h3>
<p >
Returns a new <code>SensorColour</code> object representing this arc's colour.

<p >
<h3><code>SetArcColour(<em>self</em>, <em>colour</em>)</code> (aka <code>SetArcColor</code>)</h3>
<p >
Sets this arc's colour to the given <code>SensorColour</code> object.

<p >
<h3><code>GetFromNode(<em>self</em>)</code></h3>
<p >
Returns the node from which this arc runs.

<p >
<h3><code>GetToNode(<em>self</em>)</code></h3>
<p >
Returns the node to which this arc runs.


<p >
<a name="class_DeletedException"></a>
<h2>Class <code>DeletedException</code></h2>
<p >
This is raised when a method is invoked on an object and it is no longer
valid.

<p >
<a name="fn_PollNetwork"></a>
<h2>Function <code>PollNetwork()</code></h2>
<p >
This function checks if the simulation has been paused by the user (and if so,
waits for it to be resumed again), or raises an exception (which should not
be caught) if the simulation is cancelled. This should be called periodically
during long-running tasks that do not otherwise call the API, in order to
keep the application responsive.

<p >
<a name="fn_Sleep"></a>
<h2>Function <code>Sleep(<em>seconds</em>)</code></h2>
<p >
Ceases execution for the given number of seconds (which need not be an
integer). Periodically calls <A href="#fn_PollNetwork">
<code>PollNetwork</code></A> to see if the simulation has been 
paused or cancelled.</p>         


</BODY>
</HTML>
